A user tool to debug visibility of objects #522
Conversation
robtaylor
force-pushed
the
debug-visibility
branch
from
75f2024 to
3ac44d8
Compare
| @@ -261,6 +261,7 @@ def setup(app): | |||
| app.add_config_value("autoapi_generate_api_docs", True, "html") | |||
| app.add_config_value("autoapi_prepare_jinja_env", None, "html") | |||
| app.add_config_value("autoapi_own_page_level", "module", "html") | |||
| app.add_config_value("autoapi_verbose_visibility", 0, "html") | |||
There was a problem hiding this comment.
Could we utilise logging levels instead of needing to invent our own way of configuring verbosity?
There was a problem hiding this comment.
Yep. I was just worrying about not changing the current logging behaviour too much!
There was a problem hiding this comment.
Actually, looking at this again, it adds way too much output to debug mode. I think it makes sense to have this separate for debugging visibility. Also I split the visibility debugging into two verbosity levels as usually level 1 will suffice, but allowing for deeper debugging,.
autoapi/_mapper.py
Outdated
| for child in module["children"]: | ||
| if "original_path" in child: | ||
| _trace_visibility(self.app, f"Hiding {child['full_name']} as documented at {child['original_path']}") |
There was a problem hiding this comment.
These items are hidden not because they're documented elsewhere (in fact they may not be documented anywhere) because we don't consider objects imported from the local package into a module to be part of the public API. Usually those imports are used in the implementation of a class or function in that module instead.
There was a problem hiding this comment.
ah, makes sense. I think this caught me out because i use import to populate init, and i wasn't getting documentation because the module had no top level documentation - i.e. the fix was to add a docstring at the top of init. Is this something that should be added to the docs?
Thank you, glad this is appreciated! One question I have - with the 'hide reason' enum idea, we could use this in autoapi-skip-member interface. Do you think it would make sense to add this to that api? |
robtaylor
force-pushed
the
debug-visibility
branch
from
4fc088f to
9c8d0a2
Compare
|
I'm having some odd issues running the tests in |
It seems users can get quite disoriented when switching off "undoc-members" - whole modules will stop rendering even though there may be documented objects within.
This PR adds a config that helps users to debug why items may not be rendering, and also adds an info log for the common case of the module itself missing top level documentation in init.py
Interested in your thoughts!